===============================================================================

              READ IF MAKING (OR ADDING) HORROR MODS

===============================================================================


  Optimization stack created and tuned by zebyve.


  Short version: the mod that breaks stalker entities is NOT Entity Culling.
  It is the distance-based tick optimizers, and the fix is a whitelist entry
  rather than removing anything.


-------------------------------------------------------------------------------

  1.  ENTITY CULLING IS FINE - KEEP IT ON

-------------------------------------------------------------------------------


Earlier versions of this note told you to disable Entity Culling on horror
packs. That advice was wrong, and it is retracted. Reading the mod's actual
code:


      It culls by OCCLUSION, not by distance. Entity Culling raytraces to
      decide whether solid blocks are between you and the entity. A stalker
      watching you from an open ridge 100 blocks away is in clear line of
      sight, so it is not culled. That was the scenario the old note warned
      about, and it does not happen.


      It never touches server-side AI. Its only tick-related hook is an
      @Inject into ClientLevel.tickNonPassenger - the CLIENT copy of the
      world, which drives animation and interpolation. Stalking, pathfinding
      and repositioning all run on the server thread, which Entity Culling
      does not mixin into at all.


      Worst case is cosmetic. An entity fully hidden behind terrain is not
      drawn for a frame or two. It is still there, still ticking, still
      hunting you.


Keep Entity Culling enabled. It is one of the larger FPS wins in this stack.




-------------------------------------------------------------------------------

  2.  WHAT ACTUALLY BREAKS STALKERS:  DOES IT TICK?

-------------------------------------------------------------------------------


This is the one to configure.


  The behavior:

      Does It Tick? cancels Level.guardEntityTick for any living entity more
      than 64 blocks horizontally or 32 blocks vertically from every player.
      A cancelled entity does not tick at all - no AI, no pathfinding, and
      no internal timers.


  Why that hurts horror mods specifically:

      Stalkers are built to close distance while off-screen. Frozen, they
      simply stop approaching.

      Worse, their own despawn and "give up" timers stop advancing too. Mods
      that cap concurrent spawns (Cave Dweller allows 5) count those frozen
      entities against the cap, so once enough of them are stuck out of range
      the mod goes quiet with no error in the log.


  The fix - one line in  config/does_it_tick-common.toml :

      EntitiesModIDWhiteList = ["your_mod_id", "another_mod_id"]

      Use the mod ID from the jar's META-INF/mods.toml, NOT the jar filename
      and NOT the network channel name. These differ more often than you would
      expect - Oblivious Core ships as "oblivious_core" while its channel is
      "obliviouscore", and a wrong ID fails silently.

      Whitelisted mods keep ticking at any distance. The cost is negligible:
      these packs run a handful of stalker entities, against 30-plus loaded
      chunks of everything else.


  Partial mitigation already in place:

      DisableInActiveChunks = true keeps entities ticking in chunks you have
      spent time in, via Chunk Activity Tracker. That covers your base. It
      does not cover fresh terrain, which is exactly where stalkers operate.




-------------------------------------------------------------------------------

  3.  NO SEE NO TICK  -  TWO SEPARATE HALVES

-------------------------------------------------------------------------------


Worth understanding, because the two halves obey different rules.


  Server half  (entity ticking):

      Gated behind minPlayers, which defaults to 2. At one player it is
      completely inert - every distance setting in its config does nothing.
      On singleplayer packs, Does It Tick? is doing all the work.


  Client half  (rendering) - THE IMPORTANT ONE:

      No See No Tick also injects into EntityRenderDispatcher.shouldRender and
      cancels it. That handler ignores the frustum entirely and decides purely
      on distance, so an entity you are looking straight at will not be drawn
      if it is outside the configured range.

      It does NOT respect minPlayers. The gate it checks returns "not enough
      players" on any client, whatever the player count, so this culling runs
      in singleplayer and multiplayer alike.

      It reuses the TICK distance keys for this:

            maxEntityTickDistanceHorizontal   (squared)
            maxEntityTickDistanceVertical     (raw blocks)

      The stock 48-squared / 32 values mean anything 33 blocks above or below
      your camera vanishes - trivially reached in caves, on cliffs, or in
      vertical custom dimensions. This is the real cause of "entities
      disappearing while I look right at them", and it gets misattributed to
      Entity Culling constantly.


  The fix:

      Set both above your maximum render distance so the check can never fire.

            12 chunks (192 blocks)  ->  36864 horizontal / 192 vertical
            32 chunks (512 blocks)  ->  262144 horizontal / 512 vertical

      This bundle ships the 512 values, which cover any render distance.

      Alternatively, list specific entity IDs in entityIgnoreList - that is
      checked before the distance test. Or simply remove the mod on
      singleplayer packs, where its server half is inert anyway.




-------------------------------------------------------------------------------

  4.  QUICK CHECKLIST FOR A HORROR PACK

-------------------------------------------------------------------------------


      1.  Leave Entity Culling ON.

      2.  Add every horror mod ID to EntitiesModIDWhiteList in
          does_it_tick-common.toml. Read the IDs out of mods.toml.

      3.  Keep No See No Tick's tick distances above your render distance,
          or drop the mod on singleplayer packs.

      4.  Clear out inherited whitelist entries for mods you do not have.
          They are harmless, but they hide the fact that nothing real is
          protected.

      5.  Test by walking 100+ blocks from a spawned stalker and returning.
          It should still be hunting, not standing where you left it.




===============================================================================
